SetThreadSwitcher

SetThreadSwitcher
Header:	Threads.h		Carbon status:	Supported

Installs a custom context-switching function for any thread.

OSErr SetThreadSwitcher (
    ThreadID thread, 
    ThreadSwitchUPP threadSwitcher, 
    void *switchProcParam, 
    Boolean inOrOut
);

thread: The thread ID of the thread to associate with a context-switching function.
threadSwitcher: A pointer to the context-switching function.
switchProcParam: A pointer to a thread-specific parameter that you pass to the context-switching function.
inOrOut: A Boolean value that indicates whether the Thread Manager calls the context-switching function when the specified thread switches in (True) or when it is switched out by another thread (False).

function result: A result code.

DISCUSSION

The custom switching function allows you to save context information in addition to the default context information that the Thread Manager automatically saves when it switches contexts. The default context information consists of the CPU registers, the FPU registers (if any), and the location of the threadís context.

You must actually define two context-switching functions, one for leaving a thread and another for entering a thread. When leaving a thread, you call the outer context-switching function to save additional context information. When reentering a thread, you call the inner context-switching function to restore the extra information that was saved on exit. Use the inOrOut parameter of the SetThreadSwitcher function to specify which type of context-switching function is being installed.

You can pass a different switchProcParam parameter to each thread, which allows you to write a single, application-wide custom switching function and then pass any thread-specific information when the Thread Manager calls the switching function for that thread.

The SetThreadSwitcher function automatically disables scheduling to avoid any reentrancy problems with the custom switching function. Therefore, in the custom switching function, you should make no yield calls or other calls that would cause scheduling to occur.

Do not pass a function descriptor as the threadSwitcher parameter to the SetThreadSwitcher function. As with all Thread Manager functions that pass a function pointer, you must pass the address of the function, not the address of a function descriptor. You are required to use function descriptors when you write code in the PowerPC instruction set that passes a functionís address to code that might be in the 680x0 instruction set. However, the threads in your application must all be in the same instruction setó680x0 or PowerPC. Therefore, the function identified by the threadSwitcher parameter is by definition in the same instruction set as the SetThreadSwitcher function and a function descriptor is not required.

For more information on the custom context-switching function, see the ThreadSwitchProcPtr function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.